مقارنة متعمقة بين setup.py و pyproject.toml لإدارة حزم بايثون، تغطي أفضل الممارسات واستراتيجيات الترحيل والأدوات الحديثة.
هيكل حزم بايثون: مقارنة بين setup.py و pyproject.toml - دليل شامل
لسنوات، كان ملف setup.py حجر الزاوية في إدارة حزم بايثون. ومع ذلك، تطور المشهد، وظهر pyproject.toml كبديل حديث. يستكشف هذا الدليل الشامل الاختلافات بين هذين النهجين، مما يساعدك على فهم أيهما مناسب لمشروعك وكيفية إدارة حزم بايثون الخاصة بك بفعالية.
فهم الأساسيات
ما هي حزمة بايثون؟
حزمة بايثون هي طريقة لتنظيم وتوزيع كود بايثون الخاص بك. تسمح لك بتجميع الوحدات النمطية ذات الصلة في تسلسل هرمي للدلائل، مما يجعل الكود الخاص بك أكثر نمطية وقابلية لإعادة الاستخدام والصيانة. تعتبر الحزم ضرورية لمشاركة الكود الخاص بك مع الآخرين ولإدارة التبعيات في مشاريعك.
دور البيانات الوصفية للحزمة
توفر البيانات الوصفية للحزمة معلومات أساسية حول حزمتك، مثل اسمها وإصدارها والمؤلف والتبعيات ونقاط الدخول. يتم استخدام هذه البيانات الوصفية من قبل مديري الحزم مثل pip لتثبيت حزمك وترقيتها وإدارتها. تاريخيًا، كان setup.py هو الطريقة الأساسية لتعريف هذه البيانات الوصفية.
Setup.py: النهج التقليدي
ما هو Setup.py؟
setup.py هو سكربت بايثون يستخدم مكتبة setuptools لتعريف بنية وبيانات حزمتك الوصفية. إنه ملف يتم تنفيذه ديناميكيًا، مما يعني أنه يشغل كود بايثون لتهيئة الحزمة.
المكونات الرئيسية لـ Setup.py
يتضمن ملف setup.py النموذجي المكونات التالية:
- اسم الحزمة: اسم حزمتك (على سبيل المثال،
my_package). - الإصدار: رقم إصدار حزمتك (على سبيل المثال،
1.0.0). - معلومات المؤلف والمشرف: تفاصيل حول مؤلف ومشرف الحزمة.
- التبعيات: قائمة بالحزم الأخرى التي تعتمد عليها حزمتك (على سبيل المثال،
requests >= 2.20.0). - نقاط الدخول: تعريفات لسكربتات سطر الأوامر أو نقاط الدخول الأخرى إلى حزمتك.
- بيانات الحزمة: الملفات غير البرمجية (مثل ملفات التكوين، ملفات البيانات) التي يجب تضمينها في الحزمة.
مثال على Setup.py
```python from setuptools import setup, find_packages setup( name='my_package', version='1.0.0', author='John Doe', author_email='john.doe@example.com', description='A simple Python package', packages=find_packages(), install_requires=[ 'requests >= 2.20.0', ], entry_points={ 'console_scripts': [ 'my_script = my_package.module:main', ], }, classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], ) ```إيجابيات Setup.py
- الألفة: إنها الطريقة التقليدية والمعروفة، لذا فإن العديد من المطورين على دراية بها بالفعل.
- المرونة: لأنه سكربت بايثون، فإنه يوفر درجة عالية من المرونة. يمكنك تنفيذ منطق معقد وتخصيص عملية البناء حسب الحاجة.
- قابلية التوسعة: توفر Setuptools مجموعة غنية من الميزات ويمكن توسيعها بأوامر وإضافات مخصصة.
سلبيات Setup.py
- التنفيذ الديناميكي: يمكن أن تكون الطبيعة الديناميكية لـ
setup.pyخطرًا أمنيًا، حيث إنها تنفذ كودًا عشوائيًا أثناء عملية البناء. - التبعيات الضمنية: غالبًا ما يعتمد
setup.pyعلى تبعيات ضمنية، مثل setuptools نفسها، مما قد يؤدي إلى عدم تناسق وأخطاء. - التعقيد: بالنسبة للمشاريع المعقدة، يمكن أن يصبح
setup.pyكبيرًا وصعب الصيانة. - التكوين التصريحي المحدود: يتم تعريف الكثير من البيانات الوصفية للحزمة بشكل إلزامي بدلاً من كونه تصريحيًا، مما يجعل فهمها أصعب.
Pyproject.toml: البديل الحديث
ما هو Pyproject.toml؟
pyproject.toml هو ملف تكوين يستخدم تنسيق TOML (Tom's Obvious, Minimal Language) لتعريف نظام البناء والبيانات الوصفية لحزمتك. إنه نهج تصريحي، مما يعني أنك تحدد ما تريد تحقيقه، بدلاً من كيفية تحقيقه.
الأقسام الرئيسية في Pyproject.toml
يتضمن ملفpyproject.toml النموذجي الأقسام التالية:
[build-system]: يحدد نظام البناء المراد استخدامه (على سبيل المثال،setuptools،poetry،flit).[project]: يحتوي على بيانات وصفية حول المشروع، مثل اسمه وإصداره ووصفه ومؤلفيه وتبعياته.[tool.poetry]أو[tool.flit]: أقسام للتكوينات الخاصة بالأداة (على سبيل المثال، Poetry، Flit).
مثال على Pyproject.toml (مع Setuptools)
```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = [ { name = "John Doe", email = "john.doe@example.com" } ] dependencies = [ "requests >= 2.20.0", ] [project.scripts] my_script = "my_package.module:main" [project.optional-dependencies] dev = [ "pytest", "flake8", ] [project.classifiers] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] homepage = "https://example.com" repository = "https://github.com/example/my_package" ```مثال على Pyproject.toml (مع Poetry)
```toml [tool.poetry] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = ["John Doeإيجابيات Pyproject.toml
- التكوين التصريحي: يوفر
pyproject.tomlطريقة تصريحية لتعريف البيانات الوصفية لحزمتك، مما يجعلها أسهل في الفهم والصيانة. - نظام بناء موحد: يحدد نظام البناء المراد استخدامه، مما يضمن عمليات بناء متسقة عبر بيئات مختلفة.
- إدارة تبعيات محسّنة: تتكامل أدوات مثل Poetry و Pipenv بسلاسة مع
pyproject.tomlلتوفير ميزات قوية لإدارة التبعيات. - تقليل المخاطر الأمنية: لأنه ملف تكوين ثابت، فإنه يزيل المخاطر الأمنية المرتبطة بتنفيذ الكود ديناميكيًا أثناء عملية البناء.
- التكامل مع الأدوات الحديثة: يعد
pyproject.tomlهو المعيار لأدوات تغليف بايثون الحديثة مثل Poetry و Pipenv و Flit.
سلبيات Pyproject.toml
- منحنى التعلم: قد يحتاج المطورون إلى تعلم صيغة جديدة (TOML) وطريقة جديدة للتفكير في إدارة الحزم.
- مرونة محدودة: قد لا يكون مناسبًا لعمليات البناء المخصصة للغاية التي تتطلب منطقًا معقدًا.
- الاعتماد على الأدوات: ستحتاج إلى اختيار وتعلم كيفية استخدام نظام بناء معين (مثل Setuptools، Poetry، Flit).
مقارنة بين Setup.py و Pyproject.toml
فيما يلي جدول يلخص الاختلافات الرئيسية بين setup.py و pyproject.toml:
| الميزة | Setup.py | Pyproject.toml |
|---|---|---|
| نمط التكوين | إلزامي (كود بايثون) | تصريحي (TOML) |
| نظام البناء | ضمني (Setuptools) | صريح (محدد في [build-system]) |
| الأمان | أقل أمانًا (تنفيذ ديناميكي) | أكثر أمانًا (تكوين ثابت) |
| إدارة التبعيات | أساسية (install_requires) |
متقدمة (تكامل مع Poetry, Pipenv) |
| الأدوات | تقليدية (Setuptools) | حديثة (Poetry, Pipenv, Flit) |
| المرونة | عالية | متوسطة |
| التعقيد | يمكن أن يكون مرتفعًا للمشاريع المعقدة | أقل بشكل عام |
استراتيجيات الترحيل: من Setup.py إلى Pyproject.toml
قد يبدو الترحيل من setup.py إلى pyproject.toml أمرًا شاقًا، ولكنه استثمار يستحق العناء من أجل الصيانة والاتساق على المدى الطويل. إليك بعض الاستراتيجيات التي يمكنك استخدامها:
1. ابدأ بملف Pyproject.toml بسيط
أنشئ ملف pyproject.toml أساسي يحدد نظام البناء ثم قم بترحيل البيانات الوصفية تدريجيًا من setup.py إلى pyproject.toml.
2. استخدم Setuptools مع Pyproject.toml
استمر في استخدام Setuptools كنظام بناء خاص بك، ولكن حدد البيانات الوصفية للمشروع في pyproject.toml. يتيح لك هذا الاستفادة من مزايا pyproject.toml مع الاستمرار في استخدام أداة مألوفة.
3. الترحيل إلى أداة حديثة مثل Poetry
فكر في الترحيل إلى أداة حديثة مثل Poetry أو Pipenv. توفر هذه الأدوات ميزات شاملة لإدارة التبعيات وتتكامل بسلاسة مع pyproject.toml.
مثال: الترحيل إلى Poetry
- تثبيت Poetry:
pip install poetry - تهيئة Poetry في مشروعك:
poetry init(سيرشدك هذا خلال إنشاء ملفpyproject.toml) - إضافة تبعياتك:
poetry add requests(أو أي تبعيات أخرى) - بناء حزمتك:
poetry build
4. استخدم أدوات للترحيل التلقائي
يمكن أن تساعد بعض الأدوات في أتمتة عملية الترحيل. على سبيل المثال، يمكنك استخدام أدوات لتحويل ملف setup.py الخاص بك إلى ملف pyproject.toml.
أفضل الممارسات لإدارة حزم بايثون
1. استخدم بيئة افتراضية
استخدم دائمًا بيئة افتراضية لعزل تبعيات مشروعك عن تثبيت بايثون على مستوى النظام. هذا يمنع التعارضات ويضمن أن مشروعك لديه التبعيات الصحيحة.
مثال باستخدام venv:
مثال باستخدام conda:
2. حدد التبعيات بدقة
استخدم قيود الإصدار لتحديد الإصدارات المتوافقة من تبعياتك. هذا يمنع السلوك غير المتوقع الناجم عن تحديثات المكتبات غير المتوافقة. استخدم أدوات مثل pip-tools لإدارة تبعياتك.
مثال على تحديد التبعية:
``` requests >= 2.20.0, < 3.0.0 ```3. استخدم نظام بناء متسق
اختر نظام بناء (مثل Setuptools، Poetry، Flit) والتزم به. هذا يضمن عمليات بناء متسقة عبر بيئات مختلفة ويبسط عملية التغليف.
4. وثّق حزمتك
اكتب توثيقًا واضحًا وموجزًا لحزمتك. هذا يساعد المستخدمين على فهم كيفية استخدام حزمتك ويسهل على الآخرين المساهمة في مشروعك. استخدم أدوات مثل Sphinx لإنشاء وثائق من الكود الخاص بك.
5. استخدم التكامل المستمر (CI)
قم بإعداد نظام تكامل مستمر (مثل GitHub Actions، Travis CI، GitLab CI) لبناء حزمتك واختبارها ونشرها تلقائيًا كلما تم إجراء تغييرات على الكود الخاص بك. هذا يساعد على ضمان أن حزمتك دائمًا في حالة عمل.
مثال على تكوين GitHub Actions:
```yaml name: Python Package on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install poetry poetry install - name: Lint with flake8 run: | poetry run flake8 . - name: Test with pytest run: | poetry run pytest ```6. انشر حزمتك على PyPI
شارك حزمتك مع العالم عن طريق نشرها على مؤشر حزم بايثون (PyPI). هذا يسهل على الآخرين تثبيت واستخدام حزمتك.
خطوات النشر على PyPI:
- سجل حسابًا على PyPI و TestPyPI.
- تثبيت
twine:pip install twine. - بناء حزمتك:
poetry buildأوpython setup.py sdist bdist_wheel. - رفع حزمتك إلى TestPyPI:
twine upload --repository testpypi dist/*. - رفع حزمتك إلى PyPI:
twine upload dist/*.
أمثلة من الواقع
دعنا نلقي نظرة على كيفية استخدام بعض مشاريع بايثون الشائعة لـ pyproject.toml:
- Poetry: يستخدم
pyproject.tomlلإدارة حزمه الخاصة. - Black: منسق الكود الصارم يستخدم أيضًا
pyproject.toml. - FastAPI: إطار عمل ويب حديث وسريع (عالي الأداء) لبناء واجهات برمجة التطبيقات مع بايثون يستخدمه أيضًا.
الخاتمة
يمثل pyproject.toml المعيار الحديث لإدارة حزم بايثون، حيث يوفر طريقة تصريحية وآمنة لتعريف البيانات الوصفية لحزمتك وإدارة التبعيات. بينما خدمنا setup.py بشكل جيد، فإن الترحيل إلى pyproject.toml هو استثمار يستحق العناء من أجل الصيانة والاتساق والتكامل مع الأدوات الحديثة على المدى الطويل. من خلال تبني أفضل الممارسات واستخدام الأدوات المناسبة، يمكنك تبسيط سير عمل تغليف بايثون وإنشاء حزم عالية الجودة وقابلة لإعادة الاستخدام.